This CDEF draws application-specified blocks of text within a window.
Additionally, by setting the appropriate variation codes, the Gauss CDEF can honor the owning window's text settings, honor the colors in a 'cctb' resource, display visual cues that provide the 3D-like appearance outlined in the develop 15 article "Working in the Third Dimension".
Contents of the Gauss CDEF Folder
---------------------------------
- Gauss CDEF Info: the documentation file you are reading now
- GaussCDEF.p: Pascal source code of the Gauss control definition function
- GaussCDEF.rsrc: compiled code for any 68K microprocessor of the Gauss control definition function
- GaussCDEF.π: THINK Pascal project for compiling the GaussCDEF resource
- GaussCDEF68020.rsrc: compiled code for 68020-68030-68040 microprocessors of the Gauss control definition function
- GaussCDEFStub.p: Pascal source code of the Gauss control definition function, disguised to use the JumpCDEF debugging stub
- NeoTextBox.p: Pascal source code for the NeoTextBox function, a replacement of the TETextBox Toolbox call
How to create a Gauss control
-----------------------------
The file 'GaussCDEF.rsrc' contains the compiled code of the definition procedure as a resource of type 'CDEF' with ID of 131.
To incorporate the Gauss CDEF in your applications, just open the 'GaussCDEF.rsrc' file with ResEdit (or any other suitable resource editor), copy the CDEF resource and paste it into your application's resource file.
For creating a Gauss control:
in the resource file of your project create a 'CNTL' resource and put into its ProcID field the number
where kTextDisplayID is the ID of the 'CNTL' resource and myWindow is a pointer to one of your windows.
The Gauss CDEF makes a very peculiar usage of the fields in the control template, so be sure to read the section titled 'Control template usage'.
You can also call the NewControl trap, passing it basically the same parameters you enter in the 'CNTL' resource template.
Variation Codes
---------------
A number of possible variation codes can be added to the procID field to obtain special effects. These variation codes are:
0: draw the control's title only
1: draw the control's title, followed by the number in the refCon field
2: draw only the value in the refCon field, ignoring the control's title
4: draw the text pointed to by the handle stored in the refCon field
8: draw the text using the owning window's text characteristics (font, size, style)
You can add other variation codes, henceforth called extended variation codes, to the contrlMax field of the control template. These extended variation codes are:
256: draw the control's boundary rectangle
512: draw always the control in the active (enable) state
1024: draw a 3D-like effect around the control
2048: draw ignoring the colors specified in any 'cctb' resource
Note that not all combinations of (normal and extended) variation codes are legal. If you specify one of the illegal combinations, the Gauss CDEF discards it and reverts to another legal combination by itself.
The illegal combinations and the Gauss CDEF actions are:
2 + 1, 2 + 4, 2 + 1 + 4: the CDEF reverts to the 2 variation code, discarding 1 and 4
1 + 4: the CDEF reverts to the 1 variation code, discarding 4
1024 - 256: you can't have a 3D effect without a boundary rectangle, so the CDEF discards the
1024 variation code
Control template usage
----------------------
This section describes how to set the various values of a control template to satisfy the requirements of the Gauss CDEF. The symbols '***' near to a field mean that this field is used in a non-standard way. The following table fits a 640 pixel wide screen in a 9 point monospaced font; you may need to expand the window to see the correct text wrapping.
- BoundsRect: the boundary rectangle in which the control will be drawn
- *** Value ***: the text alignment to be applied to the text, specified as follows:
0: default flush setting (resolves to left flushing on Roman script)
1: center justification on all scripts
-1: right flush on all scripts
-2: left flush on all scripts
128: full justification
note that only the low-order byte of this field is actually meaningful to the
Gauss CDEF
- Visible: whether the control is initially visible or not
- *** Max ***: the extended variation codes, as outlined above; though only the high-order
byte of this field is meaningful to the Gauss CDEF, this field should always
be greater than 128;
- *** Min ***: the effect kind (none, inset, raised) when the 1024 extended variation code
is set; the effect kind is specified as follows:
Min < -100 gives the inset effect
Min = -100 gives no effect, even if the 1024 variation code is set
Min > -100 gives the raised effect
note that this field should always be less than -2
- ProcID: [(Gauss CDEF resource ID) * 16] + variation code; note that all extended
variation codes must go into the Max field, not here
- *** RefCon ***: 32-bit value with different meanings, depending on the current set
of variation codes; these meanings are explained in the following table:
var. code meaning of RefCon
--------- -----------------
0 ignored (can be set to anything)
1 value appended to the control's title, formatted
as a signed 32-bit integer
2 value formatted as a signed 32-bit integer
4 handle to the block of text to be displayed,
allocated and disposed by the calling application
- Title: control title; ignored if the 2 or 4 variation codes are set
The following summary provides a quick overview of the above table:
max : extended variation code = 256, 512, 1024, 2048; must be max >= 128
min : effect kind (inset if < -100, raised if > -100, none if = -100); must be min <= -2
value : text justification = 0, 1, -1, -2, 128
refCon : 'real' control value or text handle
Examples
--------
Making the Gauss CDEF do what you want is not straightforward, as anyone reading the previous section can notice. In this section I'll try to explain the creation of a control using the Gauss CDEF.
The approach I think the best is: set a goal, identify the core functionality of the Gauss CDEF needed to achieve that goal, and finally decide the appearance of the Gauss CDEF.
Example #1: a progress window
+++++++++++++++++++++++++++++
Think about the Finder when it copies some files: it puts a window when it displays the number of files remaining to be copied. This window contains (besides a progress bar, which of course you can implement with the Celsius CDEF) a string of text and a count of the files remaining to be copied.
Goal: Displaying the string "Files remaining to be copied: xxx", where xxx is the number of files.
Core functionality: Draw the string and the value in the refCon
** This means adding 1 to the procID field **
Appearance: Use System's font characteristics, don't draw neither the boundary rectangle nor the 3D effect, draw always in the active state, ignore any 'cctb'
** This means adding 512 + 2048 = 2560 to the Max field **
Let's create the 'CNTL' ID 128 template like:
BoundsRect: large enough to hold all the text, including the number
{ update the counter; the Draw1Control call is needed because the Control Manager }
{ does not force a redraw on the SetControlReference calls }
filesCount := filesCount - 1;
SetControlReference(progressTextHdl, filesCount);
Draw1Control(progressTextHdl);
.....
END;
Example #2: a Tips window
+++++++++++++++++++++++++
Do you know the Tips window in the Anarchie FTP client? I'll bet you know ;-). This is another situation where the Gauss CDEF might be helpful, though it cannot (yet) display styled text.
Goal: Displaying different blocks of text that exceed the 255 characters limit.
Core functionality: Draw the handle pointed to by the refCon field
** This means adding 4 to the procID field **
Appearance: Use the owning window's font characteristics, draw the 3D inset effect (and thus the boundary rectangle), honor deactivations, honor a 'cctb'
** This means adding 8 to the procID field **
** This means adding 1024 + 256 to the Max field **
Let's create the 'CNTL' ID 128 template like:
BoundsRect: large enough to hold all the text
Value: 128 (fully justified, only to see what happens)
{ release the text, since it is not needed anymore }
ReleaseResource(tipsTextHdl);
Things to watch for
-------------------
- The contrlMax field should always be greater than 128, and the contrlMin field should always be less than -2: the Gauss CDEF need this to react properly to the changes of the text alignment you may specify with SetControlValue. I feel that a CDEF should not change these fields, since (theoretically) they are under the application's control, so I didn't burdened the code with additional checks.
- The contrlMax field transports the extended variation codes only at the control's creation, not at later times. Changing the contrlMax field after the control's creation does NOT result in the control assuming the new behavior.
- When you set the 4 variation code, allocating and releasing the storage for the text handle is your responsibility: the Gauss CDEF simply takes whatever it finds in the refCon and tries to use it as text. Moreover, don't lock this handle: the Gauss CDEF locks it and unlocks it by itself.
- The Gauss CDEF clips all its drawing to the control's boundary rectangle. This allows you to check whether the rectangle you specify is big enough or not.
- The Gauss CDEF draws the 3D-like effect (when you request it) only if the background color of the owning window is (R, G, B) = ($EEEE, $EEEE, $EEEE), as specified in the develop 15 article. If this color is different the Gauss CDEF refuses to draw the effect.
- The Gauss CDEF draws the dimmed text using the grayishTextOr transfer mode if it is available. When this is not available, the Gauss CDEF draws the text with a dithering pattern even on color screens, to achieve the disabled look.
Part codes
----------
The Gauss CDEF can only return 60 as part code to the TrackControl call.
Color mapping of 'cctb' resources
---------------------------------
When you add 2048 to the contrlMax field of the control template, the Gauss CDEF ignores any 'cctb' (control color table) resource that might be attached to the control. To have the Gauss CDEF honor your 'cctb' resource, be sure to NOT add 2048 to the contrlMax field. The Gauss CDEF maps the colors defined in your 'cctb' resource as follows:
'cctb' part code Gauss CDEF part
================ =================
Frame color Frame color
Body color Body color
Text color Text color
Thumb color Ignored
When instead you specify to ignore the 'cctb' resources, the colors are:
Frame color: black Text color: black Body color: background color of owning window
What happens when ...
---------------------
I have a Gauss control with the inset effect and I want to switch to the raised effect?
The Gauss CDEF may reposition the frame and the effect to draw the new effect within the control's boundary rectangle. However, the text stays always in the same position, regardless of which change the program requests. This is done to maintain consistency: indeed the Gauss CDEF shows the same behavior when a control intersects multiple screens, with at least one displaying the 3D effect and others not, because of different bit depths.
Low memory conditions
---------------------
The Gauss CDEF uses an offscreen drawing world to avoid unpleasant flickering effects. Since the Gauss controls may potentially span large screen areas, the CDEF does not keep the offscreen world between calls, but creates and destroys it at each drawing call. This technique does not seem to have much impact on performance.
If available memory is so low that the offscreen world cannot be created, the Gauss CDEF draws directly in the control's owning window; you should then expect to see some flickering, particularly if the control is inactive and the grayishTextOr transfer mode is not available.
Other problems may arise at initialization, when the Gauss CDEF allocates some memory for holding the number parts tables used in the number conversions. In these circumstances the CDEF behavior is unpredictable, and unfortunately a CDEF cannot return anything other than 0 from the initCntl message.
Finally, with all variation codes (excluding 4) the Gauss CDEF allocates memory for holding the text. If this memory is not available, the Gauss CDEF refuses to draw the text.
Future Directions
-----------------
A very useful feature would be specifying and drawing multistyled text. Unfortunately this would be very difficult, requiring nontrivial modifications to the NeoTextBox source code.
Credits and inspiration
-----------------------
NeoTextBox by Bryan K. Ressler, ported to Pascal by Peter N. Lewis
"International Number Formatting" by Norbert Lindenberg in develop 16
